package rbac.service;

import java.util.List;

import rbac.entity.RbacPermission;
import rbac.entity.RbacRole;
import rbac.exception.EntityDoNotExistException;


/**
 * RBAC service 接口. 负责在 service 层处理<strong>角色</strong>信息.
 * 
 * @author Huadi
 * @author Zoufengyang
 */
public interface RoleService {

	/**
	 * 通过用户 ID 获取 <code>RbacRole</code>.
	 * 
	 * @param id
	 *            角色 ID.
	 * @return <code>RbacRole</code> 类型的对象. 如果不存在, 返回 <code>null</code>.
	 */
	RbacRole getRole(Integer id);

	/**
	 * 获取所有 <code>RbacRole</code> 实体.
	 * 
	 * @return 所有 <code>RbacRole</code> 实体列表.
	 */
	List<RbacRole> getAllRoles();

	/**
	 * 持久化一个角色.
	 * 
	 * @param role
	 */
	void save(RbacRole role);

	/**
	 * 修改一个角色.
	 * 
	 * @param role
	 * @throws EntityDoNotExistException
	 *             当指定实体不存在时.
	 */
	void update(RbacRole role) throws EntityDoNotExistException;

	/**
	 * 删除一个角色.
	 * 
	 * @param role
	 *            角色实体.
	 */
	void delete(RbacRole role);

	/**
	 * 删除一个角色.
	 * 
	 * @param roleId
	 *            角色实体 ID.
	 */
	void delete(Integer roleId);

	/**
	 * 将一个权限赋予一个角色.
	 * 
	 * @param permission
	 *            权限实体.
	 * @param role
	 *            角色实体.
	 * @throws EntityDoNotExistException
	 *             当指定实体不存在时.
	 */
	void grantPermissionToRole(RbacPermission permission, RbacRole role)
			throws EntityDoNotExistException;

	/**
	 * 将一个权限赋予一个角色. 鼓励使用实体进行添加删除操作, <strong>使用此方法会导致数据库 IO 过多</strong>.
	 * 
	 * @param permissionId
	 *            权限 ID.
	 * @param roleId
	 *            角色 ID.
	 * @throws EntityDoNotExistException
	 *             当指定实体不存在时.
	 */
	void grantPermissionToRole(Integer permissionId, Integer roleId)
			throws EntityDoNotExistException;

	/**
	 * 修改一个角色.
	 * 
	 * @param roleId
	 *            角色实体 ID.
	 * @param selectedPermissionIds
	 *            新选择的权限实体 ID 集合.
	 * @throws EntityDoNotExistException
	 *             当指定实体不存在时.
	 */
	void grantPermissionToRole(Integer roleId,
			List<Integer> selectedPermissionIds)
			throws EntityDoNotExistException;

	/**
	 * 从一个角色收回一个权限.
	 * 
	 * @param permission
	 *            权限实体.
	 * @param role
	 *            角色实体.
	 * @throws EntityDoNotExistException
	 *             当指定实体不存在时.
	 */
	void revokePermissionFromRole(RbacPermission permission, RbacRole role)
			throws EntityDoNotExistException;

	/**
	 * 从一个角色收回一个权限. 鼓励使用实体进行添加删除操作, <strong>使用此方法会导致数据库 IO 过多</strong>.
	 * 
	 * @param permission
	 *            权限 ID.
	 * @param role
	 *            角色 ID.
	 * @throws EntityDoNotExistException
	 *             当指定实体不存在时.
	 */
	@Deprecated
	void revokePermissionFromRole(Integer permissionId, Integer roleId)
			throws EntityDoNotExistException;
}
